Summary

• Adds output_format parameter to the existing read_emails tool — when set to "structured", returns machine-parseable JSON instead of human-readable text
• Backward compatible: without output_format (or with "text"), behavior is unchanged
• Also adds label_ids and include_headers optional params for structured mode filtering
• Designed for consumption by workflow-builder Gmail trigger nodes (step 1 of Gmail incoming email trigger feature)

Usage

Default (text) — unchanged behavior

{ "query": "is:unread", "max_results": 5 }

Returns: "Found 5 emails:\n\nID: msg_001\nFrom: ..."

Structured JSON output

{ "query": "is:unread", "output_format": "structured", "label_ids": ["INBOX"], "max_results": 10 }

Returns:

{
  "emails": [
    {
      "id": "msg_001",
      "threadId": "thread_001",
      "historyId": "12345",
      "from": "alice@example.com",
      "to": "bob@example.com",
      "cc": "", "bcc": "",
      "subject": "Hello",
      "date": "Mon, 31 Mar 2026 10:00:00 +0000",
      "snippet": "...",
      "labels": ["INBOX", "UNREAD"],
      "isUnread": true,
      "messageId": "<abc@mail.gmail.com>",
      "body": { "text": "...", "html": "..." },
      "attachments": [{ "filename": "...", "mimeType": "...", "size": 1024, "attachmentId": "..." }]
    }
  ],
  "resultCount": 1,
  "query": "is:unread"
}

New optional parameters on read_emails

Test plan

• 14 unit tests: structured output, empty results, multi-email, body on/off, attachments on/off, query passthrough, label_ids filter, max_results cap, extra headers, valid JSON, text format default, text format explicit
• Verify black formatting passes in CI
• Integration test with workflow-builder Gmail trigger node (sibling subtask)

🤖 Generated with Claude Code